This introduces a new dereference.preservedProperties configuration that allows for custom $ref dereferencing behavior to happen where if you want to preserve, and prioritize an existing, property you can.

The use case for this is theOpenAPI 3.1 specification where because it allows you to define a description and/or summary alongside a $ref pointer, and require that that description and summary take precedence over any that may be inside of the referenced schema there is currently no way to handle this within the library currently.

For example, the following schema:

{
  required: ['name'],
  type: 'object',
  definitions: {
    name: {
      type: 'string',
      description: "Someone's name",
    },
  },
  properties: {
    name: {
      $ref: '#/definitions/name',
    },
    secretName: {
      $ref: '#/definitions/name',
      description: "Someone's secret name",
    },
  },
  title: 'Person',
}

With the existing dereferencing behavior this schema is dereferenced into the following:

{
  required: [ 'name' ],
  type: 'object',
  definitions: { name: { type: 'string', description: "Someone's name" } },
  properties: {
    name: { type: 'string', description: "Someone's name" },
    secretName: { type: 'string', description: "Someone's name" }
  },
  title: 'Person'
}

However, because in an OpenAPI 3.1 definition I would want to use "Someone's secret name" instead of "Someone's name" on the secretName property, using this new configuration I can do that:

await $RefParser.dereference(schema, {
  dereference: {
    preservedProperties: ['description'],
  }
});

{
  required: [ 'name' ],
  type: 'object',
  definitions: { name: { type: 'string', description: "Someone's name" } },
  properties: {
    name: { type: 'string', description: "Someone's name" },
    secretName: { type: 'string', description: "Someone's secret name" }
  },
  title: 'Person'
}

1. Why make this configurable instead of the default behavior? Because this seems to be specific to OpenAPI 3.1 and it could potentially be a big breaking change to how people are currently handling these sorts of cases.
2. This config is generic and has nothing specific to OpenAPI 3.1 though. Correct. This behavior would be handled upstream in consumers of the library (like swagger-parser) and conditionally feed in this config for OpenAPI 3.1 definitions.

Closes #365